Where is the default number coming from? Can we link to where the default number is actually specified? Same comment for all the default numbers below.

I have a reference here:

, but it's at the top of the file and may get lost. The default value retry values are populated from the grpc config file and I don't want to link those in here. LROs are preconfigured from the generation.

What are the default numbers if there is no gRPC config file? I guess the numbers are coming from constants in GAX ? The concern I have is if we change the default numbers in the future, we would have to change the numbers here as well, and it's very easy to forget to change here.

If there is nothing configured inside the grpc config file, the generator will create a RetrySettings with the default values with values listed above (For example: https://github.com/googleapis/google-cloud-java/blob/8452ac3a8eefa8a9e49ff83187b33be26efe6a01/java-batch/google-cloud-batch/src/main/java/com/google/cloud/batch/v1/stub/BatchServiceStubSettings.java#L518). This is what I'll call the RetrySettings default values.

Service teams can modify the grpc config file and that will provide default values for certain callables. These default values is what I'll call the callable default values. This is the RetrySettings which will be configured like: https://github.com/googleapis/google-cloud-java/blob/8452ac3a8eefa8a9e49ff83187b33be26efe6a01/java-batch/google-cloud-batch/src/main/java/com/google/cloud/batch/v1/stub/BatchServiceStubSettings.java#L507-L516

I believe they're both technically default values. The Javadoc I updated only refers the RetrySettings default values since the callable default values differ per service. I can add this explanation in so it's clearer to the readers.

The default numbers in RetrySettingsComposer is what I was referring to. If those numbers change, we would have to update the numbers here as well. But since those numbers are in the generator, I don't think it's a good idea to expose the implementation details to Gax either, I think we can leave them as they are for now.

The default numbers in RetrySettingsComposer is what I was referring to. If those numbers change, we would have to update the numbers here as well. But since those numbers are in the generator, I don't think it's a good idea to expose the implementation details to Gax either, I think we can leave them as they are for now.

Yeah, those values are set in the generator (and the generator only sets defaults for LROs). I think if we make an effort to change those, we'll have to remember to update our docs here manually. I'd like for an automated way to do that, but linking to the generator code doesn't seem ideal.

I'll keep as is for now then.

I remember that both 0 and 1 mean there is no retry from a YAQS. It's kind of already implied as maxAttempts should include the first attempt, can you please make it clear in the comment here to reduce similar confusion in the future?

Updated. Let me know if this makes more sense.

The first attempt will be considered attempt #0. I think this is true if maxAttempts is set to 0, but The first attempt will be considered attempt #1 if maxAttempts is set to 1?

The first attempt will be set as Attempt #0 (

). Every retryAttempt will create the nextAttempt class and update the attemptCount: and the shouldRetry function inside the algorithm will check if it's allowed. In this case, the first retry attempt will be attempt #1 and that will pass this check: .

I think it would make sense if I specify that maxAttempts refers to the number of retry attempts instead.